.\" $Header$
.nr yr \n(yr+1900
.af mo 01
.af dy 01
.TH ncoffsets 1 "PnetCDF PNETCDF_RELEASE_VERSION" "Printed: \n(yr-\n(mo-\n(dy" "PnetCDF utilities"
.SH NAME
ncoffsets \- print the starting/ending file offsets for netCDF variables
.SH SYNOPSIS
.ft B
.HP
ncoffsets
.nh
\%[\fB-h\fP] |
\%[\fB-x\fP] |
\%[\fB-sgr\fP]
\%[\fB-v\fP var1[,...]]
\%\fIfile\fP
.hy
.ft
.SH DESCRIPTION
\fBncoffsets\fP prints the file offsets information of variables defined in
a given netCDF file. The ending offsets reported is an exclusive offset, i.e.
1 byte more than the last byte occupied by the variable. In other words, the
ending offset is equal to the sum of starting offset and the variable size.
For record variables, only the offsets of first record are printed. Add
option \fB-r\fP to print the offsets of all records.

If no argument is given, command usage information is printed.
.SH OPTIONS
.IP "\fB-v\fP var1[,...]"
The output will only display the offset information for the specified
variables. Names of one or more variables must be provided in the
comma-delimited list which must not contain blanks or other white space
characters. The named variables must be valid netCDF variables in the input
file. The default, i.e., without this option, is to display the offset
information for \fIall\fP variables stored in the input file.
.IP "\fB-s\fP"
Print the variable size in bytes. For record variables, only the size of one
record is printed.
.IP "\fB-g\fP"
Print the gap in bytes from the previous variable. For the first defined
variable, print the gap from the end of file header. For record variables,
there is no gap between records.
.IP "\fB-r\fP"
Output the offset information for all records of the selected record variables.
Without this option, only the offsets of first record are printed.
.IP "\fB-x\fP"
Check all fixed-size variable for file space gaps in between any two
immediately adjacent variables. It prints "1" on stdout if gaps are found,
"0" for otherwise. This option disables all other options.
.IP "\fB-h\fP"
Print the available command-line options

.SH EXAMPLES
.LP
Print the file offset information for all variables in a netCDF file.

% ncoffsets -sg testfile.nc
.nf
netcdf testfile.nc {
// File format: CDF-1
// Number of dimensions: 4
// Number of variables: 4
// Number of global attributes: 0

file header:
    size   = 256 bytes
    extent = 512 bytes

dimensions:
    time = UNLIMITED // (101 currently)
    Z = 100
    Y = 100
    X = 100

fixed-size variables:
    float  square(Y, X):
           start file offset =         512
           end   file offset =       40512
           size in bytes     =       40000
           gap from prev var =         256
    double cube(Z, Y, X):
           start file offset =       40512
           end   file offset =     8040512
           size in bytes     =     8000000
           gap from prev var =           0

record variables:
    double time(time):
           start file offset =     8040512    (0th record)
           end   file offset =     8040520    (0th record)
           size in bytes     =           8    (of one record)
           gap from prev var =           0
    float  rec_var(time, Z, Y, X):
           start file offset =     8040520    (0th record)
           end   file offset =    12040520    (0th record)
           size in bytes     =     4000000    (of one record)
           gap from prev var =           0
}
.LP
Check if there are gaps in between two adjacent fixed-size variables.

% ncoffsets -x testfile.nc
0
.fi

.SH "SEE ALSO"
.LP
.BR pnetcdf (3)
.SH DATE
PNETCDF_RELEASE_DATE
.LP
